home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 1995 #1 / Amiga Plus 1995 #1.iso / fish-disketten / fish_761-770 / d765 / gambit_comp / quicktour < prev    next >
Text File  |  1994-12-13  |  16KB  |  538 lines
  1. ;; FILE        "Gambit:docs/QuickTour"
  2. ;; IMPLEMENTS    An overview of the Gambit release 1.8 for AmigaDOS 1.3/2.0
  3. ;; AUTHOR    Kenneth A Dickey
  4. ;; DATE        1992 October 2
  5. ;; LAST UPDATED    1992 October 3
  6.  
  7.  
  8. SYNOPSIS:
  9.   INTRODUCTION
  10.   INVOCATION & OPTIONS
  11.   THE READ-EVAL-PRINT LOOP (Example)
  12.   FUNCTION SYNOPSIS
  13.   STANDARDS REFERENCES
  14.  
  15.  
  16.  
  17. === INTRODUCTION ===
  18.  
  19. This is Gambit release 1.8 for the Amiga with AmigaDOS 1.3 or 2.0.
  20. This is a full implementation of Scheme with some extensions.  It
  21. conforms to IEEE P1178 and the Revised^4 Report on the Programming
  22. Language Scheme (see REFERENCES, below).  The interpreter requires 1.5
  23. MB and the compiler requires 3 MB of RAM to run (see INVOCATION &
  24. OPTIONS, below).  This document is a quick overview/reference of the 
  25. Gambit Scheme system, not a Scheme tutorial (See SchemeIntro).
  26.  
  27. This is an overview of how to use the interpreter (GSI).  See
  28. "compiler.doc" for compiler usage after you have read the material
  29. here. 
  30.  
  31.  
  32. === INVOCATION & OPTIONS ===
  33.  
  34.  
  35. INVOCATION
  36.  
  37. To invoke the interpreter, put it in your C: directory, then type its
  38. name from the CLI (See INVOCATION OPTIONS, below).  I usually name the
  39. interpreter "gsi".  You may want to name it "scheme". 
  40.  
  41. Since this is the compiler distribution, I assume that you have a hard
  42. disk and at least 3MB of RAM for development.  A gsi for the
  43. m68020+FPU is in the bin directory.  Note that there is a (freeware)
  44. companion disk with several interpreter (gsi) variants and some Scheme
  45. source code available.
  46.  
  47.  
  48. OPTIONS
  49.  
  50. You can invoke gsi with a simple command string to get a result:
  51.  
  52. > gsi "(/ 610728 1024.)"
  53. 596.4140625
  54. >
  55.  
  56. All option flags are preceeded by "--".  The most important flags are
  57. those which control how much heap space to allocate.
  58.  
  59. There are 2 heaps: a static heap and a dynamic heap.  
  60.  
  61. The static heap is where all compiled code is loaded.  Compiled code
  62. module names by convention end in ".O", source code modules in ".scm",
  63. so "foo.scm" compiles into "foo.O".  The runtime system requires ~340
  64. KB.  The compiler requires an additional 600 KB.  To set the static
  65. heap use the "-c" flag followed by the number of KB you want.  The
  66. static heap is *not* garbage collected.
  67.  
  68. The dynamic heap holds all your dynamic data structures (interpreted
  69. code and your data).  Make it as big as you can afford.  To set the
  70. dynamic heap, use the "-h" flag followed by the number of KB you want.
  71. Note that the dynamic heap is garbage collected and is divided into 2
  72. subheaps or "semi-spaces" (A Stop-and-Copy collector is currently
  73. used).  This means that if you allocate 500 KB to your dynamic heap,
  74. your live data will be up to 250 KB.  Note that the interpreter also
  75. allocates (malloc's) space for its own internal data structures.
  76.  
  77. Example: 
  78. > gsi -- -h2000 -c1000
  79. allocates 2 one-megabyte semispaces for the dynamic heap and reserves
  80. one megabyte for loading compiled code (e.g. the compiler).
  81.  
  82. See file "docs/gsi.man" for further details and options.
  83.  
  84.  
  85.  
  86. === THE READ-EVAL-PRINT LOOP (Example) ===
  87.  
  88. >gsi
  89.  
  90. Gambit (v1.8)
  91.  
  92. : (define (fact x)
  93.     (cond ((= x 0) 1)
  94.           ((= x 1) 1)
  95.           ((> x 1) (* (fact (- x 1)) x))
  96.           (else    (error "argument must be positive"))))
  97. fact
  98.  
  99. : (trace fact)
  100. fact
  101.  
  102. : (fact 10)
  103. Entry (fact 10)
  104. |Entry (fact 9)
  105. | Entry (fact 8)
  106. |  Entry (fact 7)
  107. |  |Entry (fact 6)
  108. |  | Entry (fact 5)
  109. |  |  Entry (fact 4)
  110. |  |  |Entry (fact 3)
  111. |  |  | Entry (fact 2)
  112. |  |  |  Entry (fact 1)
  113. |  |  |  ==> 1
  114. |  |  | ==> 2
  115. |  |  |==> 6
  116. |  |  ==> 24
  117. |  | ==> 120
  118. |  |==> 720
  119. |  ==> 5040
  120. | ==> 40320
  121. |==> 362880
  122. ==> 3628800
  123. 3628800
  124.  
  125. : (untrace fact)
  126. fact
  127.  
  128. : (pp fact)    ;; NOTE: 'x is alpha-converted to 'x.1 by the macro-expander
  129. (lambda (x.1)
  130.   (cond ((= x.1 0) 1)
  131.         ((= x.1 1) 1)
  132.         ((> x.1 1) (* (fact (- x.1 1)) x.1))
  133.         (else (error "argument must be positive"))))
  134. #f
  135.  
  136. : (define f fact)
  137. f
  138.  
  139. : (define fact "not the factorial function")
  140. fact
  141.  
  142. : (f 5)
  143. *** ERROR IN f -- Operator is not a PROCEDURE
  144. (fact (- x 1))
  145.  
  146. 1: ,?
  147. ,?        : Summary of commands
  148. ,+ and ,- : Move to next or previous frame of continuation
  149. ,<n>      : Move to particular frame (<n> <= 0)
  150. ,b        : Display frames of continuation (i.e. backtrace)
  151. ,p        : Display procedure attached to current frame
  152. ,e        : Display subproblem of current frame
  153. ,l        : Display list of local variables accessible in current frame
  154. ,t        : Transfer to top-level REP loop
  155. ,d        : Transfer to previous REP loop
  156. ,r        : Return from REP loop
  157. ,q        : Quit
  158.  
  159. 1: ,b
  160. 0    f                         (fact (- x 1))
  161. -1   (top level)               (f 5)
  162. -2   ##read-eval-print
  163. -3   ##dynamic-env-bind
  164. -4   ###_kernel.startup
  165.  
  166. 1: ,p
  167. #[procedure f] =
  168. (lambda (x.1)
  169.   (cond ((= x.1 0) 1)
  170.         ((= x.1 1) 1)
  171.         ((> x.1 1) (* (fact (- x.1 1)) x.1))
  172.         (else (error "argument must be positive"))))
  173.  
  174. 1: ,l
  175. x.1 = 5
  176.  
  177. 1: (- x.1 1)
  178. 4
  179.  
  180. 1: fact
  181. "not the factorial function"
  182.  
  183. 1: (set! fact f)
  184. #[undefined]
  185.  
  186. 1: ,r (fact (- x.1 1))
  187. 120
  188.  
  189. : (list (gensym) (gensym) (gensym))
  190. (g1 g2 g3)
  191.  
  192. : (put 'bob 'eyes 'blue)
  193. #f
  194.  
  195. : (put 'mary 'hair 'blond)
  196. #f
  197.  
  198. : (get 'bob 'eyes)
  199. blue
  200.  
  201. : (get 'mary 'eyes)
  202. #f
  203.  
  204. : (define (series term)
  205.     (let ((sum 0) (stop #f))
  206.       (FUTURE (let loop ((i 0))
  207.                 (if (not stop)
  208.                   (begin (set! sum (+ sum (term i))) (loop (+ i 1))))))
  209.       (lambda (msg)
  210.         (cond ((eq? msg 'value) sum)
  211.               ((eq? msg 'stop)  (set! stop #t))
  212.               (else             (error "unknown message" msg))))))
  213. series
  214.  
  215. : (define pi (series (lambda (i) (/ 4. ((if (odd? i) - +) (+ (* i 2) 1))))))
  216. pi
  217.  
  218. : (pi 'value)
  219. 3.141419882340216
  220.  
  221. : (pi 'value)
  222. 3.1415194471477133
  223.  
  224. : (pi 'value)
  225. 3.1416300745380195
  226.  
  227. : (pi 'value)
  228. 3.1415798589941843
  229.  
  230. : (pi 'stop)
  231. #[undefined]
  232.  
  233. : (pi 'value)
  234. 3.1415815090449892
  235.  
  236. : (pi 'value)
  237. 3.1415815090449892
  238.  
  239. : ,q
  240.  
  241.  
  242.  
  243.  
  244.  
  245. === FUNCTION SYNOPSIS ===
  246.  
  247.  
  248. Here is a quick reference of the signatures of provided functions.
  249. Aside from Extensions, there is no attempt at completeness.  It is
  250. assumed that the user has a copy of R^4RS or the IEEE/ANSI standard.
  251.  
  252. Notation:
  253.   <object>    any Scheme data object.
  254.   <object>*    zero or more objects
  255.   <object>+    one or more objects
  256.   [<object>]    optional object
  257.  
  258.  
  259. ; EXTENSIONS
  260.  
  261.   (EXIT) -- exit the interpreter.
  262.  
  263.   (##SYSTEM <string>) -- Executes CLI command string
  264.     e.g. (##system "dir #?.scm")
  265.  
  266.   (TRACE <proc>+ )   -- turns trace on  for <proc>(s) {SYNTAX}.
  267.   (UNTRACE <proc>* ) -- turns trace off for <proc>(s) {SYNTAX}.  With
  268.     no <proc> specified, turns off tracing for all trace'd procedures.
  269.  
  270.   (ERROR <message> <object>* ) -- invokes the debugger.  ",?" for help.
  271.  
  272.   (PP <object> [<output-port> [<width>]]) -- Pretty print object.  
  273.     Prints source for interpreted code.
  274.  
  275.   (PRETTY-PRINT <object> [<output-port> [<width>]] ) -- like PP, but does
  276.     *not* print source for code.
  277.  
  278.   (GENSYM [<symbol-or-string>] ) -- generates a symbol.
  279.     Examples:
  280.       (gensym)        -> g1
  281.       (gensym 'foo) -> foo2
  282.       (gensym)        -> g3
  283.  
  284.   (PUT <symbol> <key> <value>)     -- Known generally as "putprop"
  285.   (GET <symbol> <key>)    -> <value> -- Known generally as "getprop"
  286.     Examples:
  287.       (put 'groceries 'beans 37)
  288.       (put 'groceries 'milk 2)
  289.       (get 'groceries 'beans)     -> 37
  290.  
  291.   (LOAD <string>) -- rather than "foo.scm" <string> may be "foo",
  292.    which looks first for "foo.O", then "foo.scm"
  293.  
  294.   (EVAL <expression>) -- If you don't know what this does, you should
  295.     probably not use it.  You probably don't need to use it anyway...
  296.  
  297.   (SET-GC-REPORT <boolean>) -- If set to #t, reports when a storage
  298.     reclamation occurs.  If set to #f (the default), gc is not reported.
  299.  
  300.   (OPEN-INPUT-STRING <string>)  -> <output-string-port>
  301.   (OPEN-OUTPUT-STRING)        -> <input-string-port>
  302.   (GET-OUTPUT-STRING <input-string-port>) -> <string>
  303.  
  304.   (##WEAK-CONS <obj1> <obj2>)    -> a weak cons
  305.   (##WEAK-PAIR? <object>)    -> #t or #f
  306.   (##WEAK-CAR <weak-pair>)    -> <obj1> or #f
  307.   (##WEAK-CDR <weak-pair>)    -> <obj2>
  308.     Weak pairs are a special object that behavies like a cons cell,
  309.     except that the car pointer is weak.  This means that if no 
  310.     "strong" ppointer is referencing an object denoted by the car
  311.     slot, it will be collected after gc.  When collected, the car's
  312.     value becomes #f.  The cdr slot is `normal'.  Note that a
  313.     weak-pair is *not* a pair-- you must use the ##weak-* functions.
  314.     I.e. you cannot take the CAR of a weak-pair, you must use
  315.     ##weak-car.  Weak pointers are useful to keep track of things
  316.     that you don't want to stay around just because you are keeping
  317.     track of them (e.g. elements of a set with some property).
  318.  
  319.   (FUTURE <expression>) -> <future>
  320.     Futures are a multi-processing construct.  The value is potentially
  321.     calculated in parallel with other computations.  Futures may be
  322.     stored in data structures.  Their value is guarenteed where it is
  323.     first used ("touching" is implicit in this implementation).
  324.  
  325. Extensions for compiler users:
  326.  
  327.   (COMPILE <string> [ <option>* ] ) 
  328.     options:
  329.       ASM causes a commented assembly file to be generated
  330.       PVM creates a file of Portable Virtual Machine instructions
  331.       VERBOSE causes a report of compile time actions to be displayed
  332.       REPORT  reports on global variable usage
  333.       DEBUG compiles in debug information (takes up a lot of space!) so that
  334.             compiled code can be debugged like interpreted code.
  335.  
  336.   (MAKE-UNSCANNED-VECTOR <num-slots>) -- Creates a vector which is not
  337.     scanned by the collector.  Useful for stashing C pointers and non-Scheme
  338.     binary values.
  339.   (UNSCANNED-VECTOR? v)        -> #t or #f
  340.   (UNSCANNED-VECTOR-LENGTH uv)    -> <num-slots>
  341.   (UNSCANNED-VECTOR-SET! uv index val)
  342.   (UNSCANNED-VECTOR-REF  uv index) -- you should probably never use this!
  343.     [The implementation is in "runtime/gsi.scm"].
  344.  
  345.   (REGISTER-FOR-FINALIZATION <object> <thunk>) -- After the next
  346.     collection where <object> is no longer referenced, executes
  347.     <thunk>.  Note that <thunk> cannot refer to <object> or it will
  348.     never be collected.  This is useful for invoking destructors on C
  349.     malloc'ed storage when windows close, etc.  Note that it is
  350.     considered bad form to allocate storage within <thunk>.  [The
  351.     implementation is in "runtime/gsi.scm"].
  352.  
  353.   
  354. ; SYNTAX
  355.  
  356.   (LAMBDA <name> <exp>+ )
  357.   (LAMBDA (<name>* ) <exp>+ )
  358.   (AND <object>*)
  359.   (OR  <object>*)
  360.   (IF <test-exp> <if-true> [<if-false>] )
  361.   (COND (<test> <exp>* )... [(ELSE <exp>+)] )
  362.   (CASE <key-exp> ((<datum>+ ) <exp>* )... [(ELSE <exp>+)] )
  363.   (LET [<name>] ( (<vname> <value-exp>) ) <body-exp> )
  364.   (LET*   ( (<vname> <value-exp>) ) <body-exp> )
  365.   (LETREC ( (<vname> <value-exp>) ) <body-exp> )
  366.   (BEGIN <expression>+ )
  367.   (DO ( (<var> <init> <step>)... ) ( <test> <exp>* ) <exp>* )
  368.   ;; Note also R^4RS syntax, below
  369.  
  370. ; IEEE Scheme
  371.  
  372.   (NOT <object>)
  373.   (BOOLEAN? <object>)
  374.  
  375.   (EQV? <obj1> <obj2>)
  376.   (EQ? <obj1> <obj2>)
  377.   (EQUAL? <obj1> <obj2>)
  378.  
  379.   (PAIR? <object>)
  380.   (CONS <obj1> <obj2>)
  381.   (CAR <pair>)
  382.   (CDR <pair>)
  383.   (SET-CAR! <pair> <object>)
  384.   (SET-CDR! <pair> <object>)
  385.   (CAAR  <list>)   (CADR  <list>)   (CDAR  <list>)   (CDDR <list>)
  386.   (CAAAR <list>)   (CAADR <list>)   (CADAR <list>)   (CADDR <list>)
  387.   (CDAAR <list>)   (CDADR <list>)   (CDDAR <list>)   (CDDDR <list>)
  388.   (CAAAAR <list>)  (CAAADR <list>)  (CAADAR <list>)  (CAADDR <list>)
  389.   (CADAAR <list>)  (CADADR <list>)  (CADDAR <list>)  (CADDDR <list>)
  390.   (CDAAAR <list>)  (CDAADR <list>)  (CDADAR <list>)  (CDADDR <list>)
  391.   (CDDAAR <list>)  (CDDADR <list>)  (CDDDAR <list>)  (CDDDDR <list>)
  392.   (NULL? <object>)
  393.   (LIST? <object>)
  394.   (LIST <object>* )
  395.   (LENGTH <list>)
  396.   (APPEND <list>+ )
  397.   (REVERSE <list>)
  398.   (LIST-REF <list> <index>)
  399.   (MEMQ  <object> <list>)
  400.   (MEMV  <object> <list>)
  401.   (MEMBER <object> <list>)
  402.   (ASSQ  <object> <alist>)
  403.   (ASSV  <object> <alist>)
  404.   (ASSOC <object> <alist>)
  405.  
  406.   (SYMBOL? <object>)
  407.   (SYMBOL->STRING <symbol>)  (STRING->SYMBOL <string>)
  408.  
  409.   (NUMBER? <object>)
  410.   (COMPLEX? <object>)
  411.   (REAL? <object>)
  412.   (RATIONAL? <object>)
  413.   (INTEGER? <object>)
  414.   (EXACT? <number>)     (INEXACT? <number>)
  415.   (=  <number>+ )
  416.   (<  <number>+ )  (>  <number>+ )
  417.   (<= <number>+ )  (>= <number>+ )
  418.   (ZERO? <number>)
  419.   (POSITIVE? <number>)  (NEGATIVE? <number>)
  420.   (ODD? <number>)       (EVEN? <number>)
  421.   (MAX <number>+ )      (MIN <number>+ )
  422.   (+ <number>+ )
  423.   (* <number>+ )
  424.   (- <number>+ )
  425.   (/ <number>+ )
  426.   (ABS <number>)
  427.   (QUOTIENT <num1> <num2>)  (REMAINDER <num1> <num2>)
  428.   (MODULO <num1> <num2>)
  429.   (GCD <number>* )          (LCM <number>* )
  430.   (NUMERATOR <rational>)    (DENOMINATOR <rational>)
  431.   (FLOOR <number>)          (CEILING <number>)
  432.   (TRUNCATE <number>)       (ROUND <number>)
  433.   (RATIONALIZE <num1> <num2>)
  434.   (EXP <number>)            (LOG <number>)
  435.   (SIN <number>)   (COS <number>)   (TAN <number>)
  436.   (ASIN <number>)  (ACOS <number>)  (ATAN <number> [<number>])
  437.   (SQRT <number>)
  438.   (EXPT <num1> <num2>)
  439.   (MAKE-RECTANGULAR <num1> <num2>)  (MAKE-POLAR <num1> <num2>)
  440.   (REAL-PART <number>)       (IMAG-PART <number>)
  441.   (MAGNITUDE <number>)       (ANGLE <number>)
  442.   (EXACT->INEXACT <number>)  (INEXACT->EXACT <number>)
  443.   (NUMBER->STRING <number>)  (STRING->NUMBER <string>)
  444.  
  445.   (CHAR? <object>)
  446.   (CHAR=?  <char1> <char2>)  (CHAR-CI=?  <char1> <char2>)
  447.   (CHAR<?  <char1> <char2>)  (CHAR-CI<?  <char1> <char2>)
  448.   (CHAR>?  <char1> <char2>)  (CHAR-CI>?  <char1> <char2>)
  449.   (CHAR<=? <char1> <char2>)  (CHAR-CI<=? <char1> <char2>)
  450.   (CHAR>=? <char1> <char2>)  (CHAR-CI>=? <char1> <char2>)
  451.   (CHAR-ALPHABETIC? <character>)
  452.   (CHAR-NUMERIC?    <character>)
  453.   (CHAR-WHITESPACE? <character>)
  454.   (CHAR-UPPER-CASE? <character>)  (CHAR-LOWER-CASE? <character>)
  455.   (CHAR->INTEGER <character>)     (INTEGER->CHAR    <integer>)
  456.   (CHAR-UPCASE   <character>)     (CHAR-DOWNCASE    <character>)
  457.  
  458.   (STRING? <object>)
  459.   (MAKE-STRING <length> [<character>] )
  460.   (STRING <character>+ )
  461.   (STRING-LENGTH <string>)
  462.   (STRING-REF <string> <index>)
  463.   (STRING-SET! <string> <index> <character>)
  464.   (STRING=?  <string1> <string2>)  (STRING-CI=?  <string1> <string2>)
  465.   (STRING<?  <string1> <string2>)  (STRING-CI<?  <string1> <string2>)
  466.   (STRING>?  <string1> <string2>)  (STRING-CI>?  <string1> <string2>)
  467.   (STRING<=? <string1> <string2>)  (STRING-CI<=? <string1> <string2>)
  468.   (STRING>=? <string1> <string2>)  (STRING-CI>=? <string1> <string2>)
  469.   (SUBSTRING <string> <start-index> <end-index>)
  470.   (STRING-APPEND <string>+ )
  471.  
  472.   (VECTOR? <object>)
  473.   (MAKE-VECTOR <length> [<object>] )
  474.   (VECTOR <object>* )
  475.   (VECTOR-LENGTH <vector>)
  476.   (VECTOR-REF  <vector> <index>)
  477.   (VECTOR-SET! <vector> <index> <object>)
  478.  
  479.   (PROCEDURE? <object>)
  480.   (APPLY <procedure> <arg>* <arg-list>)
  481.   (MAP   <procedure> <list>+ )
  482.   (FOR-EACH <procedure> <list>+ )
  483.   (CALL-WITH-CURRENT-CONTINUATION <one-argument-procedure>)
  484.  
  485.   (CALL-WITH-INPUT-FILE  <string> <procedure>)
  486.   (CALL-WITH-OUTPUT-FILE <string> <procedure>)
  487.   (INPUT-PORT? <object>)  (OUTPUT-PORT? <object>)
  488.   (CURRENT-INPUT-PORT)    (CURRENT-OUTPUT-PORT)
  489.   (OPEN-INPUT-FILE  <string>)       (OPEN-OUTPUT-FILE <string>)
  490.   (CLOSE-INPUT-PORT  <input-port>)  (CLOSE-OUTPUT-PORT <output-port>)
  491.   (EOF-OBJECT? <object>)
  492.   (READ [<input-port>] )
  493.   (READ-CHAR [<input-port>] )
  494.   (PEEK-CHAR [<input-port>] )
  495.   (WRITE   <object> [<output-port>] )
  496.   (DISPLAY <object> [<output-port>] )
  497.   (NEWLINE [<output-port>] )
  498.   (WRITE-CHAR <character> [<output-port>] )
  499.  
  500.  
  501. ; R4RS Scheme
  502.  
  503.   (LIST-TAIL <list>)
  504.   (STRING->LIST <string>)
  505.   (LIST->STRING <list-of-characters>)
  506.   (STRING-COPY  <string>)
  507.   (STRING-FILL! <string> <character>)
  508.   (VECTOR->LIST <vector>)
  509.   (LIST->VECTOR <list>)
  510.   (VECTOR-FILL! <vector> <object>)
  511.   (DELAY <expression>)
  512.   (FORCE <promise>)
  513.   (WITH-INPUT-FROM-FILE <string> <thunk>)
  514.   (WITH-OUTPUT-TO-FILE  <string> <thunk>)
  515.   (CHAR-READY? [<input-port>] )
  516.   (LOAD <string>)
  517.   (TRANSCRIPT-ON <string>)
  518.   (TRANSCRIPT-OFF)
  519.   (DEFINE-SYNTAX <name> <transformer-spec>)    -- High-Level macros (only)
  520.   (LET-SYNTAX    ( <syntax-spec>* ) <exp>+ )
  521.   (LETREC-SYNTAX ( <syntax-spec>* ) <exp>+ )
  522.  
  523.  
  524.  
  525. === STANDARDS REFERENCES ===
  526.  
  527.  
  528. IEEE Standard 1178-1990. "IEEE Standard for the Scheme Programming
  529. Language", IEEE, New York, 1991, ISBN 1-55937-125-0 [1-800-678-IEEE:
  530. order # SH14209].  -- now also an ANSI standard.
  531.  
  532. W. Clinger and J. Rees, eds., "Revised^4 Report on the Algorithmic
  533. Language Scheme", ACM LISP Pointers IV, 3 (July-September 1991).
  534.  
  535.  
  536.  
  537. ;;            --- E O F ---            ;;
  538.